src/interfaces/IFeeDistributor.sol (1)

38-39: Consider adding event declarations.
The documentation references events like NodesContractUpdated, PayerContractUpdated, RebatesPercentageUpdated, and UsdcTokenUpdated, but they are not defined in this interface. Defining them here would allow external tools and third-party integrators to rely on a fully specified interface.

Also applies to: 46-47, 60-61, 68-69

src/interfaces/IPayerReportManager.sol (1)

143-144: Mismatch between documentation and declared events.
The documentation for settleUsageBatch states "Emits a UsageSettled event", but the code only declares PayerReportPartiallySettled or PayerReportFullySettled. Consider updating the documentation or adding the missing event to avoid confusion.

src/PayerRegistry.sol (3)

108-110: Consider maximum array bounds for usage settlement.
In settleUsage, there is no explicit upper limit on the length of payerList. Large arrays in a single transaction may exceed gas limits. A chunking approach or batch processing could be safer.

---

405-414: Enforcing minimum deposit amounts to be strictly greater than defaults.
This is a strict policy. If there's a legitimate need to lower these values in the future, the contract won't permit it. You may want to allow administrators to set it equal to or less than the default if system requirements change.

---

607-618: Deposit validation prevents depositing while in withdrawal.
Currently, _validateAndProcessDeposit reverts if there's an active withdrawal request. If there is no policy reason to forbid depositing during withdrawal, consider relaxing or clarifying this constraint.

src/interfaces/IPayerRegistry.sol (10)

65-66: Correct the reference to reflect 'PayerRegistry' instead of 'Payer contract'.

The doc block states “Interface for errors emitted by the Payer contract”, but everything in this file pertains to the PayerRegistry.

A quick fix could be:

- * @notice Interface for errors emitted by the Payer contract.
+ * @notice Interface for errors emitted by the PayerRegistry contract.

---

234-243: Fix doc mismatch for the withdrawal event name.

The doc says “Emits WithdrawalRequest” (line 240), but the actual event name declared (line 60) is WithdrawalRequested.

Proposed fix in the doc:

- * Emits `WithdrawalRequest`.
+ * Emits `WithdrawalRequested`.

---

301-308: Synchronize the emitted event name for setting the fee distributor.

The doc indicates “Emits FeeDistributorUpdated” (line 305), but the declared event (line 12) is FeeDistributorSet.

Proposed fix in the doc:

- * Emits `FeeDistributorUpdated`.
+ * Emits `FeeDistributorSet`.

---

309-316: Synchronize the emitted event name for setting the payer report manager.

The doc indicates “Emits PayerReportManagerUpdated” (line 313), but the declared event (line 36) is PayerReportManagerSet.

Proposed fix in the doc:

- * Emits `PayerReportManagerUpdated`.
+ * Emits `PayerReportManagerSet`.

---

317-324: Synchronize the emitted event name for setting the node registry.

The doc indicates “Emits NodeRegistryUpdated” (line 321), but the declared event (line 24) is NodeRegistrySet.

Proposed fix in the doc:

- * Emits `NodeRegistryUpdated`.
+ * Emits `NodeRegistrySet`.

---

325-332: Synchronize the emitted event name for setting the USDC token address.

The doc indicates “Emits UsdcTokenUpdated” (line 329), but the declared event (line 48) is UsdcTokenSet.

Proposed fix in the doc:

- * Emits `UsdcTokenUpdated`.
+ * Emits `UsdcTokenSet`.

---

337-338: Synchronize the emitted event name for updating the minimum deposit.

The doc says “Emits MinimumDepositUpdated” (line 337), but the declared event (line 18) is MinimumDepositSet.

Proposed fix in the doc:

- * Emits `MinimumDepositUpdated`.
+ * Emits `MinimumDepositSet`.

---

342-348: Synchronize the naming and doc for minimum registration amount.

The doc says “Sets the minimum deposit amount required for registration” (line 342), while the parameter is described as newMinimumRegistrationAmount (line 343). Also, the doc states “Emits MinimumRegistrationAmountUpdated” (line 345), but the actual event is MinimumRegistrationAmountSet (line 21).

Proposed fix in the doc:

- * @notice Sets the minimum deposit amount required for registration.
+ * @notice Sets the minimum registration amount required to become a payer.
...
- * Emits `MinimumRegistrationAmountUpdated`.
+ * Emits `MinimumRegistrationAmountSet`.

---

350-356: Synchronize the emitted event name for updating the withdrawal lock period.

The doc says “Emits WithdrawalLockPeriodUpdated” (line 353), but the declared event (line 57) is WithdrawalLockPeriodSet.

Proposed fix:

- * Emits `WithdrawalLockPeriodUpdated`.
+ * Emits `WithdrawalLockPeriodSet`.

---

358-364: Synchronize the emitted event name for updating the transfer fees period.

The doc says “Emits TransferFeesPeriodUpdated” (line 361), but the declared event (line 39) is TransferFeesPeriodSet.

Proposed fix:

- * Emits `TransferFeesPeriodUpdated`.
+ * Emits `TransferFeesPeriodSet`.

src/PayerRegistry.sol (1)

176-194: 🛠️ Refactor suggestion

Withdrawal logic is structured well.
The contract correctly locks withdrawal amounts and enforces a cooldown; however, you might wish to allow depositing while a withdrawal is pending (if that aligns with your business logic) or explicitly document why no deposits are allowed during the withdrawal lock.

src/PayerRegistry.sol (4)

395-411: Evaluate strict requirement for new minimum deposit/registration amounts.

Currently, newMinimumDeposit and newMinimumRegistrationAmount must strictly exceed default constants (_DEFAULT_MINIMUM_DEPOSIT_AMOUNT_MICRO_DOLLARS / _DEFAULT_MINIMUM_REGISTRATION_AMOUNT_MICRO_DOLLARS). This could reduce flexibility if the admin wants to lower these limits or set them to exactly the default in the future. Consider relaxing the requirement or making it configurable to allow equality or lower values if needed.

Also applies to: 416-428

---

610-613: Enforce more explicit decimal handling.

You treat USDC amounts as microdollars (e.g., 10,000,000 = $10). While this is workable, consider adding comments or inline clarifications in _validateAndProcessDeposit (and elsewhere) confirming the decimal relationship between "micro_dollars" and USDC (6 decimals). This helps future maintainers avoid confusion about deposit amounts and rounding behavior.

---

604-615: Improve naming for clarity.

_validateAndProcessDeposit is used for both self-deposit and third-party deposit, but the method name doesn’t clearly convey the difference between these scenarios. Consider renaming or adding more explicit in-code documentation about how it handles external donors vs. payer self-deposits.

---

655-657: Offer test coverage for negative and edge-case balances.

Given that payers can accumulate negative balances (and remain active unless fully negative), add or plan for thorough testing around:

1. Very large usage amounts pushing balances far negative.
2. Edge-case scenarios for withdrawal with existing debt.

Would you like me to prepare a set of test stubs that cover overflow edge cases, negative balance transitions, and partial debt settlement?

Also applies to: 672-674

src/interfaces/IPayerRegistry.sol (2)

240-241: Update documentation to match event names.

The docstring references events like WithdrawalRequest while the contract emits WithdrawalRequested. Similarly, it mentions WithdrawalFinalized but keep an eye on consistency in doc comments across the interface and the implementation contract to avoid confusion.

Also applies to: 260-261

---

342-346: Clarify docstring for minimum registration vs. deposit.

Both setMinimumDeposit and setMinimumRegistrationAmount mention “... required for registration” in the doc comments. Consider removing references to registration in setMinimumDeposit or clarifying that the deposit minimum is also used for subsequent deposits, not just initial registration.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

src/PayerRegistry.sol (1)

228-230: ⚠️ Potential issue

Potential overflow/underflow for very large usage values.
As previously noted in older reviews, subtracting uint64 values from an int64 balance can overflow if usage is extremely large (beyond int64 range). This contract does not appear to enforce a maximum usage limit. Consider capping usage or performing explicit range checks to avoid accidental overflow.

Below is an example check to ensure usage fits within int64 bounds:

 for (uint256 i = 0; i < payerList.length; i++) {
     ...
+    require(usageAmountsList[i] <= type(int64).max, "Usage exceeds int64 limit");
     if (!_payerExists(payerList[i])) continue;
     ...
 }

Also applies to: 278-281, 292-294

src/PayerRegistry.sol (2)

501-505: Avoid reverting in getIsActivePayer when the payer doesn’t exist.
Currently, this function reverts if a payer is missing. In typical scenarios, a query like “is this account active?” would safely return false for unknown payers, rather than throwing an error. Relaxing the revert to a boolean false may improve developer UX and integration ergonomics.

---

603-614: Consider emitting a dedicated deposit event for clarity.
_validateAndProcessDeposit updates the payer’s balance and emits a generic PayerBalanceUpdated event. A more explicit Deposit event can help index deposit-specific data in off-chain indexers and analytics, resulting in clearer on-chain bookkeeping.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro